Skip to main content

Troubleshooting Broken Image & Media Paths

This guide explains why Docusaurus builds fail (502 errors) when adding images or videos, and how to use the correct path structure.

1. The Build Failure​

Symptoms​

After adding a new image or video to an MDX file, the site shows a 502 Bad Gateway error.

How to Diagnose​

Check the container logs for broken image URL or couldn't be resolved errors:

sudo docker logs docusaurus | grep -i "broken image"

Common Error Message: Error: Markdown image with URL "/opt/docker-data/.../image.png" in source file "..." couldn't be resolved to an existing local image file.

2. The Cause: Absolute vs. Static Paths​

The Wrong Way (Absolute Server Paths)​

Many users try to use the full path where the file is stored on the server: ![Description](/opt/docker-data/apps/docusaurus/site/static/img/my-image.png)

Why this fails: Docusaurus builds the site inside the container. It doesn't understand your server's folder structure. It only looks inside its own project folders.

The Right Way (Static Asset Paths)​

Docusaurus has a special folder called static. Anything inside that folder is served at the root / of your website.

If your image is at: static/img/my-image.png The path in your MDX should be: /img/my-image.png

3. The Solution​

Step 1: Place assets in static​

Ensure your images and videos are uploaded to the correct location:

  • /opt/docker-data/apps/docusaurus/site/static/img/

Step 2: Use relative static paths​

Update your .mdx files to use the shorthand path:

Markdown Image:

![My Image](/img/my-image.png)

HTML Video:

<video controls width="100%">
  <source src="/img/my-video.mp4" type="video/mp4" />
</video>

4. YouTube and External Media​

Markdown syntax ![]() is specifically for images. It will not embed a video player for YouTube links.

To embed YouTube, use an <iframe>:

<iframe 
  width="100%" 
  height="315" 
  src="https://www.youtube.com/embed/VIDEO_ID" 
  frameborder="0" 
  allowfullscreen>
</iframe>

5. Verification​

After fixing paths, restart the services:

sudo docker restart docusaurus

Monitor the logs: sudo docker logs -f docusaurus. If the build finishes with [SUCCESS], the 502 error will clear.